home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / utils / trace27 / trace.man < prev   
Text File  |  1994-10-01  |  7KB  |  199 lines
  1. TRACE(1)                 Programmer's Manual             TRACE(1)
  2.  
  3.  
  4.  
  5. NAME
  6.      trace - trace system calls made by a process
  7.  
  8. SYNOPSIS
  9.      trace [-help] [-o fname] [-l len] [-p psp] [-abcefinrstvwxy]
  10.      [ command options ... ]
  11.  
  12. DESCRIPTION
  13.      Trace is a system utility that produces a listing of the
  14.      MS-DOS requests made by a process.  It is a useful debugging
  15.      tool that can be used on any executable program.  Trace can
  16.      also be used to provide a better understanding of the inter-
  17.      nal workings of many programs.  A utility with the same name
  18.      and similar functionality is provided with SunOS.
  19.  
  20.      Trace can monitor either a command passed as an argument,
  21.      all the resident processes in the system or a process with a
  22.      given program segment prefix (PSP).  In all cases it creates
  23.      a file (trace.log by default) where each system call and its
  24.      arguments made by the process(es) monitored are printed.  A
  25.      number of options control the detail of information printed.
  26.  
  27. OPTIONS
  28.      -a   Monitor all system calls.  By default the following
  29.           functions are traced: disp_out (0x02), direct_out
  30.           (0x06), disp_string (0x09), flush (0x0d),
  31.           set_current_disk (0x0e), get_current_disk (0x19),
  32.           set_dta (0x1a), drive_info (0x1c), set_vector (0x25),
  33.           parse_name (0x29), get_date (0x2a), get_time (0x2c),
  34.           set_time (0x2d), get_dta (0x2f), get_version (0x30),
  35.           cntrl_brk (0x33), get_flag (0x34), get_vector (0x35),
  36.           mkdir (0x39), rmdir (0x3a), chdir (0x3b), creat (0x3c),
  37.           open (0x3d), close (0x3e), read (0x3f), write (0x40),
  38.           unlink (0x41), lseek (0x42), chmod (0x43), ioctl
  39.           (0x44), dup (0x45), dup2 (0x46), getcwd (0x47), alloc
  40.           (0x48), free (0x49), realloc (0x4a), exec (0x4b), exit
  41.           (0x4c), get_code (0x4d), findfirst (0x4e), findnext
  42.           (0x4f), set_psp (0x50), get_psp (0x51), sysvars (0x52),
  43.           child_psp (0x55), get/set_time (0x57),
  44.           get/set_alloc_str (0x58), tmpfile (0x5a).  create_new
  45.           (0x5b).  get_psp (0x62), open (0x6c), Functions not
  46.           included in the above list are printed by default using
  47.           their function number without their arguments.
  48.  
  49.      -b   Print the interrupt branch address.  Each line is pre-
  50.           ceded by the address on which the MS-DOS interrupt was
  51.           generated.
  52.  
  53.      -c   Only a summary count of all calls is produced at the
  54.           end of the program run.  No detailed information is
  55.           given.  One line is produced for each function used.
  56.           The line contains the function number in hexadecimal,
  57.           the symbolic function name and the number of times the
  58.           function was called.
  59.  
  60.  
  61.  
  62.  
  63. Printed 9/1/94           1 October 1994                         1
  64.  
  65.  
  66.  
  67. TRACE(1)                 Programmer's Manual             TRACE(1)
  68.  
  69.  
  70.  
  71.      -e   Trace between exec calls.  Unless this option is given,
  72.           monitoring is disabled until the child process ter-
  73.           minates, when a program performes an exec call .
  74.  
  75.      -f   Calls are prefixed with the MS-DOS function call
  76.           number.
  77.  
  78.      -h   A short help list on the program options is displayed
  79.           on the standard output.
  80.  
  81.      -i   Calls are prefixed with the process-id of the process
  82.           that performed them.  This is the PSP address of the
  83.           program under MS-DOS.
  84.  
  85.      -l L Specify the number of bytes printed for input / output
  86.           calls.  Up to L bytes of data will be printed.  The
  87.           default number is 15.
  88.  
  89.      -n   Functions that are not normally printed are printed by
  90.           a short descriptive name rather than their function
  91.           number.
  92.  
  93.      -o F The output file for tracing information is F instead of
  94.           the default trace.log.  Note that F can also be a dev-
  95.           ice name such as con or prn.
  96.  
  97.      -p P Trace a process with process-id (PSP address) P.  This
  98.           is usually a terminate and stay resident (TSR) utility.
  99.           To obtain the PSP address of the program use a memory
  100.           display utility such as dosmem or mi or run trace with
  101.           the -i option.
  102.  
  103.      -r   Produce a register dump on functions that do not have
  104.           their arguments printed.
  105.  
  106.      -s   Print strings on various functions.  The functions
  107.           affected are:
  108.  
  109.           + For all input/output functions follow the function
  110.             call with the string that was read or written.  The
  111.             maximum length of the string is specified with the -l
  112.             option.  The string is followed by an ellipsis (...)
  113.             if it contains more characters than the maximum
  114.             length.  The default length is 15 characters.  Non
  115.             ASCII data is not printed unless the -x option is
  116.             given.
  117.  
  118.           + The ioctl calls that get the device mode have it
  119.             printed as symbolic constants.
  120.  
  121.           + The get and set filemode functions have the file mode
  122.             printed as a string similar to that produced by the
  123.             Unix ls -l command.
  124.  
  125.           + The directory name returned by the get current
  126.  
  127.  
  128.  
  129. Printed 9/1/94           1 October 1994                         2
  130.  
  131.  
  132.  
  133. TRACE(1)                 Programmer's Manual             TRACE(1)
  134.  
  135.  
  136.  
  137.             directory function is printed.
  138.  
  139.           + The files returned by the find first / find next
  140.             functions are printed together with their associated
  141.             information.
  142.  
  143.      -t   Prefix all system calls with time in the form of
  144.           hh:mm:ss.
  145.  
  146.      -v   Verbose option.  This option will produce the highest
  147.           amount of data. It is equivalent to specifying the
  148.           -aefinrstwx options.  A trace line printed using these
  149.           options will resemble the following:
  150.           22:11:56 2c40 40 2C50:4B26 write(1, 3200:923E, 1) =
  151.           1  "r"
  152.           The contents of the line are: the time, PSP address of
  153.           the calling process, function call number, address that
  154.           generated the function call, the function, its argu-
  155.           ments, the return value and the string written.
  156.  
  157.      -w   Errors from MS-DOS functions are printed in word form
  158.           (i.e. symbolically) rather than as error codes.
  159.  
  160.      -x   Data printed under the -s option will be printed even
  161.           if it is not ASCII in hexadecimal form.
  162.  
  163.      -y   Close log file after every write.  Useful for debugging
  164.           programs that crash.
  165.  
  166. SEE ALSO
  167.      D. Spinellis.  Trace: A tool for logging operating system
  168.      call transactions.  Operating Systems Review, 28(4):56-63,
  169.      October 1994.
  170.      Ralf Brown and Jim Kyle.  The PC Interrupt List.  Addison-
  171.      Wesley, 1991.
  172.  
  173. AUTHOR
  174.      (C) Copyright 1991, 1994 Diomidis Spinellis.  All rights
  175.      reserved.
  176.      e-mail: dspin@leon.nrcps.ariadne-t.gr
  177.      snail mail: SENA S.A., Kyprou 27, GR-152 37 Filothei,
  178.      Greece.
  179.  
  180. BUGS
  181.      Most FCB calls and a number of ioctl requests are not
  182.      decoded.
  183.  
  184.      There should be an option to merge consequentive write(2)
  185.      requests.
  186.  
  187.      The system call used by trace to get the exit code of the
  188.      process run is also traced.
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Printed 9/1/94           1 October 1994                         3
  196.  
  197.  
  198.  
  199.